Graphics Plus/Graphics Plus.iso/msdos/raytrace/pov/gen/bstone/bstone.doc

Text File | 1994-04-20 | 31KB | 1,018 lines

BUILDSTONE BASIC V0.9(test)


0. Introduction
===============

Buildstone Basic is a special-purpose Basic interpreter:
Many fans of the popular raytracer POV use to write programs for
producing input files. This interpreter was prepared to make
time between idea and POV input a little bit shorter.

Since B'stone has got the ability to handle numbers and vectors as well
as objects and CSG shapes, you don't have to take care about the data
structure for your program. Please look at the examples for an idea of
what can be done with B'stone.

To use B'stone Basic successfully you should have some experiences with
a Basic interpreter and the POV raytracer V2.0. B'stone uses POV 2.0
syntax.


0.1 Some Properties
===================
- no graphic preview
- data types: scalar, vector, object, scalar array, vector array,
  bit array
- scalar and vector functions and operations
- translation, scaling and rotation of objects
- translation, scaling and rotation of objects within the object space
- ability to "connect the dots"
- management of CSG objects (union, intersection, difference)
- automatic calculation of bounding shapes
- debug options, tracing, break
- bugs, of course.


0.2 Hardware / OS
=================
The program has been tested with 386/486 DOS machines on DOS 5/6.
A Coprocessor is not strictly required, but it is recommended.
Bstone doesn't use XMS/EMS and runs in a DOS-box under Windows 3.
Later versions will probably come with ANSI compatible source code.

Tip: The author prefers a multitasking / graphic environment (Windows)
running a command shell (DOS-box) and a text editor simultaneous. With
this configuration you should be able to drag and drop or cut and
paste text lines from the editor into the Basic interpreter directly.

Bug: There is an annoying bug which is probably system-related: The break
key, CTRL-C, seems to work properly with DOS 5.0, but not with DOS 6.0.
Machines running DOS 6 have been reported to hang up after CTRL-C. The
reason is unknown.




1. Starting / Finishing the Program
===================================
Type "bstone" at the OS prompt. A short message from the author,
option infos and the command line prompt appears. Now you can type
the commands you like.
Type
    10 print "Hello world !"
    goto 10

and you will see what is going on.
To finish B'stone type

    end


1.1 Options
===========
Valid options are:

    -h,-?    Get a help message.
    -d    Turn debugging on. Writes the log / status file
                "bstone.log" during a session.
    -b    Disable CTRL-C. If not switched off, you can stop
        program execution with CTRL-C. This will slow down
        a MS-DOS version. (See hardware/OS hints also.)
    -s    Disable automatic save. If not disabled, B'stone will
        write your actual program text into the file
        "bstone.sav" at the end of a session.
    -l    Disable automatic listing. If not disabled, you will
        get an automatic listing after every command.
        file    Loads the command script "file".


2. Basic
========
B'stone is a Basic INTERPRETER. If a line starts with a number,
for instance

    10 print "Hello world !"

B'stone accepts this as a part of a program. If you type it without
the line number

       print "Hello world !"

B'stone will execute the print command immediately and you will get
the well-known message.
In both cases B'stone translates the line into an internal tokenized
representation doing syntax checks. If the line is not OK you
will receive an error message before the line is executed or stored.
This works also for command scripts. Command scripts are implemented
as an input redirection from a file.


2.1 Writing / Starting a Basic Program
======================================
You may write your program with your favourite text editor. It should
look like this:

    10 print "Hello world"
    20 REM This is a comment

B'stone doesn't care about upper and lower cases of the letters or
the order of the line numbers.
You can start bstone with the filename as an option or you may type
at the command prompt:

    load "c:/bstone/my_file.bas"

The other way is typing in the program lines directly.
To see your program or parts of it use:

    list
(or)    list 10
(or)    list 10,20

If automatic listing is enabled (it is enabled by default) you can look
at a specific line and its neighbours:

    30 #

To delete a program line / program lines use:

    new
(or)    10
(or)    delete 10
(or)    delete 10,20

To replace program line 30 with line 10:

    30 10

Finally, you want to start execution:

    run
(or)    run 10
(or)    goto 10

If the programs hangs up due to an infinite loop and break is not
disabled, press CTRL-C. If nothings happens probably important data
has been overwritten or your operating system or hardware is incompatible
to the CTRL-C handler (it has been tested for 386/486 computers with DOS 5).
Unfortunately these bugs are hard to detect and have a good chance
to survive.

For a detailed explanation of commands see the next chapters.
Look at the examples and experiment to learn B'stone Basic.


2.2 Data Types
==============
B'stone knows the following data / variable types: scalar, vector,
object, scalar array, vector array, bit array.
String is not a real data type, but it will be explained here, too.

Scalar (float):
---------------
    constants:    10  10.3  10.3e-4  PI
    variables:    A  ALPHA  C3  X_3

When an integer number is required the digits after the decimal point
are cut off.

Vector:
-------
    constants:    <1,1,-2.3>  <A,2,ALPHA>  V0  VX  VY  VZ
    variables:    A^  ALPHA^  C3^  X_3^

V0,VX,VY,VZ are predefined vector constants.
An at-sign '@' preceding scalar and vector values means that they are
in degrees (otherwise they are in radiant):
@< 90, 90, 90 > is equal to < @90, @90, @90 > or < PI/2, PI/2, PI/2 >.

Object:
-------
    variables:    A$  ALPHA$  C3$  X_3$

This data type represents simple objects and CSG objects, textures
and bounding shapes.
Scalars, vectors and arrays may be used in expressions, objects not.

Array:
-------
    Scalar Array:    A[3]  ALPHA[3][7]  C3[A]  X_3[10][10]

    Vector Array:    A^[3]  ALPHA^[3][7]  C3^[A]  X_3^[10][10]

    Bit Array:    BIT A[3]  BIT ALPHA[7][4]

The purpose of bit arrays is to save memory if only the setting
information of a point field is needed. Since scalar or vector
arrays use 8 Bytes per value, they could be too large.
There is a need for memory allocation for arrays. You have to use the
"DIM" command _before_ using an array:

    DIM A[10][10]
    DIM A^[2]
    DIM BIT A[256][8]

The indices start with 1 and end with n. In later versions of B'stone
this may have been changed to 0 and n-1.

If you use a scalar or vector variable for an array with and without
indices, the variable without indices points to the location in the array
where the last access took place. This is a side effect which can
lead to confusion.

Example:
    DIM A[10]
    LET A[4]=3
    PRINT "A[4]",A


String
------
Strings are no specific data type, because you can not use them as the
left hand side in assignments. Strings always look like:

"Hello world !"

There are special characters for strings:

\    this can be used to write strings, "which are longer \
    than one line." Use it only in case of emergency.
\\    Backslash
\n    Newline
\t    Tabulator



2.3 Vector and Scalar Functions
===============================
The syntax for functions is FUNCTION ( arguments ), for instance
SQRT(3), square root of 3. Most of them are standard. See Appendix A.
The TRANSFORM functions are used for coordinate transformations.


2.4 Expressions
===============
You can make scalar and vector expressions, for instance
    (A*B+A^*B^)*SQRT(3)
Take care about the precedence of the operators and use brackets if
you are not sure.
Objects or strings are not allowed in expressions.
Look at the operator table (Appendix B).


2.5 Commands
============
B'stone permits one command per command line only.
Object managing commands have got a separate chapter.
For a short reference of commands see Appendix C.

2.5.1 Miscellanous Commands
---------------------------
REM This is a comment
This is used to write comments into programs. Example:
    10 REM Never ending story....
    20 GOTO 20

NEW
clears anything, program and variables. You get a "blank sheet".


2.5.2 Program Development
-------------------------
LIST
displays the complete program you wrote on the screen. After one
screenfull it stops and expects <ENTER> to continue.

LIST 100
lists any program line beginning with 100.

LIST 100,200
lists any program line from 100 to 200.

DELETE 100
deletes any program line beginning with 100.
ATTENTION: You delete a single line with typing the line number only.

DELETE 100,200
deletes any program line from 100 to 200.


2.5.3 Debugging
---------------
STOP
stops program execution. You can continue execution by using the
CONT command. STOP will be used for breakpoints and for stopping the
program for input (there is no input command !).
Example:

    C1> RUN
        ...stopped at line 30
    10  REM Input of A required
    20  STOP
    30  LET B=A

    C2> A=1700
    C3> CONT


CONT
continues program execution after STOP or CTRL-C.

TRACE 0
disable execution tracing.

TRACE 1
enable execution tracing. The program stops after each executed line,
shows the line, and eventually data used there. The program continues
after pressing <ENTER>. If you type n<ENTER> the program stops. It can
be continued using the CONT command.
Other trace levels are defined but only important for the developer.


2.5.4 Execution Control
-----------------------
RUN
starts program execution with the least line number.

RUN 10
starts program execution with line number 10. There is a little
difference to GOTO 10: RUN will clear the GOSUB stack.

END
terminates program execution, if END is part of a Basic program.

GOTO 10
jumps to line number 10. Extensive use of GOTO will produce so
called confusing "spaghetti code". You should try to avoid this
problem with discipline.
If the line number GOTO is searching for doesn't exist, GOTO jumps to
the next higher one. This is also true everywhere line numbers are
used.
Goto doesn't permit variable line numbers.


GOSUB 1000
makes a call to the subroutine at line 1000. The last command of this
subroutine must be RETURN.
Example:
    10 A=0
    20 GOSUB 100
    30 GOSUB 100
    40 GOSUB 100
    50 END
    100 A=A+1
    110 PRINT "Call No ",A
    120 RETURN

GOSUB doesn't permit variable line numbers.

RETURN
returns from subroutine.

IF A<B THEN PRINT "A is less than B"
Conditional execution of the command after THEN. It will be used
very often together with GOTO. The condition is a scalar expression.
If the expression is 0 then the condition becomes false and the command
after THEN will not be executed.
There is one exception with GOTO: Since IF is used with GOTO
very often, B'stone accepts the following:
IF A<B GOTO 10


FOR i=1 TO 10
FOR i=1 TO 10 STEP 2
NEXT i
These are loop commands. They can be used in programs only. The loop
body is between the FOR state and the corresponding NEXT command. The
reference is done by the loop variable (i in this case). The loop
variable must not be an array.
The step is the value the loop variable is increased by.
If there is no STEP keyword the step value is 1.
Example:

    10 FOR i=1 to 10 STEP 2
    20 PRINT "I=",i
    30 NEXT i
    40 REM End of the loop

If execution reaches line 10, the step value (2) and the end value (10)
are stored. If execution reaches line 30 it will be checked if i+2
is greater than 10. If true the program jumps to the following line.
If false i becomes i+2 and the program jumps to line 20.
The numbers 1 3 5 7 9 are printed. i remains 9.
In this example:

    10 FOR i=1 to 10
    20 PRINT "I=",i
    30 NEXT i

the numbers from 1 to 10 will be printed.
The loop body will be executed at least once, e.g.

    10 FOR i=1 to 0
    20 PRINT "I=",i
    30 NEXT i

will print I=1.



2.5.5 Loading / Saving Command Scripts
--------------------------------------
LOAD "c:/bstone/my_file.bas"
LOAD "my_file.bas"
Loads the command script mentioned. You don't need to specify
the full path name, relative path names are permitted.
Loading works like typing in. (It is just another input stream.)

END
The exact meaning of END without leading line number is
"the input stream has to be closed". Of course this terminates
B'stone when you are typing this command from console.

SAVE "c:/bstone/my_file.bas"
SAVE "my_file.bas"
Saves the program into the file. The second form saves the file
into your current working directory. SAVE has been implemented quite
similar to LIST.

SAVE 100 "c:/bstone/my_file.bas"
Saves the program beginning with line 100.

SAVE 100,200 "my_file.bas"
Saves the program from line 100 to line 200.

SAVE TRACE "my_file.bas"
Saves the complete program, but with automatic line numbers. It doesn't
use the original line numbers but counts them beginning with 10 and a
step of 10. Jumps (GOTO, GOSUB) are "normalized" also, but nothing else.
Use this if you are confused by line numbers with short distances.


2.5.6 Writing and Displaying Data
---------------------------------
FOPEN
FOPEN "c:/bstone/pov.inc"
Fopen opens a file or device for FPRINT. The first form redirects the
FPRINT output to screen. The second form opens the mentioned file.
Every output written to the file will be appended to the end
of the old file (mode "w+").

DELETE "c:/bstone/pov.inc"
Similar to FOPEN, but deletes the file before using it.

PRINT expressions
FPRINT expressions
These commands are similar. They use different output devices.
PRINT writes to the screen, FPRINT writes to a file opened with
FOPEN or DELETE. The default is the standard output device.
Every data type, including strings, can be printed. Data terms are
separated with commas.
Empty expressions are not printed and will produce an error message.
Examples are:
    PRINT a*b
    FPRINT "#declare MyObj = ",MyObj$
    PRINT "The cross product of ",a^," and ",b^," is ",a^# b^


2.5.7 Data Management (objects excluded)
----------------------------------------
DIM A[10]
The DIM command is necessary for reserving memory for arrays. At the
time of translation the translator knows nothing about the size of
arrays. You must tell the program how much elements your arrays
contain and which range of indices should be used.
Examples:
    Scalar array:    DIM A[10][10]
    Vector array:    DIM B^[8]
    Bit array:    DIM BIT C[256][10][8]
Remember, the indices of arrays start with 1 and end with the values
given above. You receive an error message if you are out of this range.
Be careful: it is not checked if you use the bit fields always in the
right context. This isn't good style but will work:
    DIM BIT C[256][8]
    PRINT C[1][1]

LET A=B
A=B
The LET command refers to a data transfer operation, called
"assignment". Assignment with and without LET is equal. The LET
keyword has been introduced due to tradition. You can assign
data of the same type only (except for some object assignments which
will be explained later), e.g:

    LET A=3
    LET B=17*4+SQRT(C)*Z[17]
    LET D[4]=A^*B^
    LET A^=<1,1,1>
    LET B^[3][9]=C^# D^+Z^[12]
    LET A$=B$



2.6 Object Management
=====================
Things described until now make Basic working, but the core of
B'stone are object operations. Objects are the things you call
"object" or "texture" in POV.
They have a quite complex data structure in their background.
Amongst other things there are pointers to texture and bounding
objects and a string to define the object as a "sphere { <0,0,0> 1 }"
or "Gold_Metal". Every object keeps its own coordinate system to
store the effects of a sequence of translations, rotations and
scalings. You can make unions, intersections or differences of them
with simple operations and within loops, a thing often requested
by POV users. In fact, this data structure is approx. 100 Bytes long.
But this is for your interest only. Usually you will not see these
things except for running out of memory.


2.6.1 Initialize Objects
------------------------
DELETE A$
brings the object A$ into its initial state.

DELETE TEX A$
deletes the texture object corresponding to A$.

DELETE BOUND A$
deletes the bounding shape of A$.

A$="box {<-1,-1,-1><1,1,1>}"
LET B$="My_Obj"
These assignments define the appearance of the objects. These strings
will be copied to the POV file directly. Example:

    LET A$="My_declared_Object"
    PRINT A$

and you should see

    object { My_declared_Object
    }

The default string is "sphere { <0,0,0> 1 }". Try to define your
objects so that they are fitting into a unit box (lower left:
<-1,-1,-1>, upper right: <1,1,1> ) and scale, translate and rotate
them afterwards into the position and size you want. This is the
only way to make automatic bound calculation and ctds possible.
Example:

    WRONG:    LET A$="sphere { <0,0,0> 2 }"
    OK:    LET A$="sphere { <0,0,0> 1 }"
        LET A$=SCALE( A$, <2,2,2> )



A$=<1,1,1>
LET B$=VX+VY+VZ
You can set the location of your object directly.
Example:

    LET A$="My_Obj"
    LET A$=<17,17,3>+<1,1,0>
    PRINT A$

and you should see

    object { My_Obj
     translate <18,18,3>
    }



2.6.2 Assigning Objects
-----------------------
The basic operation for objects are assignments. You can assign
objects or object creating functions to objects. You can assign
textures and bounding shapes, too. Since there is a fair amount
of object creating functions, the author breaks the principle of
showing examples and uses the terms "object" and "object_function"
instead.
Here is a list of possible assignments:

object = object
Simple object assignment. Example: LET A$=B$

object = object_function
Assignment of object functions. (see the next chapters)
Example: LET A$=PLANE(V0,VY)


TEX object = object
TEX object = object_function
Assignment of an object or an object function to a texture. Currently
the only sensible object functions for textures are other textures.
Example: LET TEX A$ = TEX B$
The default string for texture objects is "MyTexture".


BOUND object = object
BOUND object = object_function
Assignment of an object or an object function to a bounding object.
Example: LET BOUND A$=B$
Do not use bounding shapes or textures in objects assigning to a bound.



2.6.3 Object Functions
----------------------
Object functions are parts of objects or manipulations of objects or
sets of objects. Common object functions are translation, scaling
and rotation. Object functions can be used as the right hand side in
assignments only. You can not print them or use them instead of
object variables within other object functions.


2.6.3.1 Miscellanous Object Functions
-------------------------------------
These are some obvious functions, for instance:
Object itself:                A$
Texture of an object:            TEX A$
Bounding shape of an object:        BOUND A$

Examples:
    LET B$=A$
    LET B$=TEX A$
    LET B$=BOUND A$


2.6.3.2 Translation, Scaling, Rotation
--------------------------------------
These are the usual object transformation functions:
TRANSLATE,SCALE,ROTATE.

Examples:
    LET B$=TRANSLATE(A$,<1,1,1>)
    LET B$=SCALE(A$,<3,3,3>)
    LET C$=ROTATE(A$,<@30,0,0>)

Remember, you must specify degrees with the preceding '@' if you
want to use them.


2.6.3.3 Translation, Scaling, Rotation in Object Space
------------------------------------------------------
Every object has its own coordinate system. Imagine you are sitting
in an airplane: the x arrow points to the propeller, the y arrow
goes through the roof of the cabin and the z arrow is the left wing.
The object space transformation functions take this coordinate
system as their base.

You are somewhere in space:
DELETE Cessna$
LET Cessna$=ROTATE(Cessna$,<0,@45,0>)

Fly a short time straight on.
LET Cessna$=TRANSLATE#(Cessna$,<100,0,0>)

Fly a roll (fasten your seatbelt!):
LET Cessna$=ROTATE#(Cessna$,<@180,0,0>)

Transform your Cessna into a 747 Jumbo Jet:
LET Jumbo$=SCALE#(Cessna$,<100,100,100>)

Watch the development of the results (PRINT Cessna$,Jumbo$).


2.6.3.4 Object Creating Functions (PLANE,CTDS)
----------------------------------------------
PLANE(A^,B^)
Creates a plane with A^ as reference point and B^ as normal vector.
Example:
    LET A$=PLANE(<0,0,1>,-VZ)

PLANE(P1^,P2^,P3^)
Makes a plane from the three points. The resulting normal vector creates
a LEFT hand system with the vectors P2^-P1^,P3^-P1^.
Example:
    LET A$=PLANE(V0,VX,VY)
This is the same as "plane { z, 0 }".

CTDS(A$,B$)
Assumes that A$ and B$ are transformed unit spheres and creates a
connecting cone.
Example:
    DELETE A$
    LET B$=TRANSLATE(A$,VX)
    LET B$=ROTATE(B$,<0,@45,0>)
    LET B$=SCALE#(B$,<0.2,0.2,0.2>)
    LET C$=CTDS(A$,B$)

CTDS(A$,B$,C$)
(As many objects as you like) Assumes that all objects are transformed
unit spheres and creates a union of connecting cones.
Example:
    DELETE A$
    LET B$=TRANSLATE(A$,VX+VY)
    LET B$=SCALE#(B$,<0.5,0.5,0.5>)
    LET C$=TRANSLATE(A$,-VX+VZ)
    LET C$=SCALE#(C$,<0.3,0.3,0.3>)
    LET D$=CTDS(C$,A$,B$)


2.6.3.4 CSG Objects
-------------------
With B'stone you can create CSG objects or add objects to CSG objects.

UNION(A$,B$,C$)
(As many objects as you like) Creates a union of the objects.
Example:
    LET D$=UNION(A$,B$,C$)

SECT(A$,B$,C$)
(As many objects as you like) Creates an intersection of the objects.
Example:
    LET D$=SECT(A$,B$,C$)

DIFF(A$,B$,C$)
(As many objects as you like) Creates a difference of the objects.
Example:
    LET D$=DIFF(A$,B$,C$)


ADDOBJ(A$,B$,C$)
(As many objects as you like) Adds the objects B$ and C$ to an
existing union, intersection or difference A$. If A$ is not a CSG
object ADDOBJ will create a new union. Be careful with ADDOBJ, using
it within loops could lead to memory problems.
Example:
    DELETE A$
    LET A$=ADDOBJ(A$,B$)
    LET A$=ADDOBJ(A$,C$)



2.6.4 Bounding Shape Calculation
--------------------------------
B'stone is able to calculate a bounding box for objects and CSG
objects.
Within unions it looks for a bounding box containing every included
element. For intersections it will take the smallest element and for
differences B'stone will use the first one.
It is required that every untransformed, unbounded primitive fits
into the { <-1,-1,-1>< 1, 1, 1>} box.
Calculation of bounding boxes considers bounding shapes existing
already. If the highest object in the hierarchy has got a bounding
shape yet, delete it with DELETE BOUND A$.

The command is BOUND A$.

Example:
    DELETE A$
    LET A$=SCALE(A$,<10,2,1>)
    LET BOUND B$=A$
    DELETE C$
    LET C$=TRANSLATE(C$,-12*VX)
    LET M$=UNION(B$,C$)
    BOUND M$
    PRINT M$



3. Conclusions
==============

3.1 Note from the Author
========================
Well, I know Basic is slow and absolutely out. But it was a simple way
to combine some algorithms with an easy-to-implement programming
language. Probably most programmers have seen Basic before and are
able to write Basic programs or can learn it with small effort.

I would welcome a different realization, too. For instance,
it could be possible to create a C++ library. If you plan such thing,
please inform me.

Ideas how to improve the program and the documentation are always
appreciated. I am interested in what you are doing with it.
My current Internet address is: [e-mail], but
do not mail every question you have, please. Look into the source code
or books first and try to experiment.
If you find bugs send the "buggy" Basic text and a short comment.
I will collect bugs and make a new program version available when I
have the time.

I'd like to apologize for my English. I am not a native English
speaker ( in fact, I am an East German ).



3.2 Official Information
========================
Using this program is free.
The package containing the program, the documentation etc. may be
copied freely, but in its original state only. The author will not
agree to any commercial distribution including shareware / freeware
samplers.
There is no warranty for any part of the program or documentation.





Appendix A: Vector and Scalar Functions
=======================================

Result: scalar value
--------------------
ABS(scalar_val)            absolute value
ABS(vector_val)            absolute value (size)
RND(scalar_val)            random value in the range 0..scalar_val
VX(vector_val)            x component of vector_val
VY(vector_val)            y component of vector_val
VZ(vector_val)            z component of vector_val
SIN(scalar_val)            sinus
COS(scalar_val)            cosinus
TAN(scalar_val)            tangens
ASIN(scalar_val)        arcus sinus
ACOS(scalar_val)        arcus cosinus
ATAN(scalar_val)        arcus tangens
EXP(scalar_val)            exponent e^x
LOG(scalar_val)            natural logarithm ln
SQRT(scalar_val)        square root
SQR(scalar_val)            sqare x^2
POW(scalar_val,scalar_val)    power, a^b

Result: vector value
--------------------
RND(vector_val)            random vector in the range V0..vector_val
VX(object_var)            x component of object_var
VY(object_var)            y component of object_var
VZ(object_var)            z component of object_var
ROT(vector_val,vector_val)    rotation (arg2^ rotated by arg1^)
SCA(vector_val,vector_val)    uneven scaling
PER(vector_val,vector_val)      perpendicular (arg1^ dot (result^-arg2^) = 0)

TRANSFORM#(vector_val,vector_val_x,vector_val_y,vector_val_z)
                transformation of the 1st vector
                from the given coordinate
                system into standard system

TRANSFORM(vector_val,vector_val_x,vector_val_y,vector_val_z)
                transformation of the 1st vector
                from standard coordinates
                into the given system



Appendix B: Operators
=====================
Operators are sorted by precedence. Operators in the same group have
the same precedence.

Result: scalar value
--------------------
scalar_val && scalar_val        logical AND
scalar_val || scalar_val        logical OR

scalar_val <  scalar_val        less
scalar_val <= scalar_val        less or equal
scalar_val =  scalar_val        equal (scalars)
vector_val =  vector_val        equal (vectors)
scalar_val >  scalar_val        greater
scalar_val >= scalar_val        greater or equal
scalar_val != scalar_val        not equal (scalars)
vector_val != vector_val        not equal (vectors)

scalar_val +  scalar_val        addition
scalar_val -  scalar_val        subtraction

scalar_val *  scalar_val        product
vector_val *  vector_val        dot product
scalar_val /  scalar_val        division
scalar_val %  scalar_val        modulo

- scalar_val                unary minus
! scalar_val                logical NOT
@ scalar_val                value in degrees
( scalar_val )                bracketing
F( arguments )                functions

Result: vector value
--------------------
vector_val +  vector_val        vector addition
vector_val -  vector_val        vector subtraction

scalar_val *  vector_val        scaling
vector_val #  vector_val        cross product

- vector_val                negative vector
@ vector_val                vector of degrees
( vector_val )                bracketing
< scalar_val,scalar_val,scalar_val >    definition of a vector
F( arguments )                functions



Appendix C: Commands
====================

Miscellanous Commands
---------------------
(nothing)            empty command
REM text            comment
NEW                clear anything (program and variables)

Program Development
-------------------
LIST                list program
LIST val            list program beginning with line number
LIST val,val                    list program from-to
DELETE val            delete beginning with line number
DELETE val,val            delete from-to

Debugging
---------
STOP                stop program execution
CONT                continue program execution
TRACE val            set trace level (0: no tracing)

Execution Control
-----------------
RUN                start execution
RUN val                start execution at line number
END                terminate program
GOTO val            jump to line number
GOSUB val            call line number (subroutine)
RETURN                return from call
IF val THEN command        if-then branch
FOR var=val TO val        counting loop
FOR var=val TO val STEP val    counting loop with step
NEXT var            end of counting loop

Loading / Saving Command Scripts
--------------------------------
LOAD string            load command script from file
END                end of a script file or program
SAVE string            save program into file
SAVE val string            save program beginning with line number
SAVE val,val string        save program from-to
SAVE TRACE string        save program with automatic line numbers

Writing and Displaying Data
---------------------------
FOPEN                open display for fprint
FOPEN string            open file for fprint
DELETE string            re-write and open file for fprint
PRINT expressions        display expressions
FPRINT expressions        write expressions into file

Data Management (see Appendix D also)
-------------------------------------
DIM array            allocate memory for array
LET variable=expression        assignment
variable=expression        assignment



Appendix D: Object Handling
===========================

DELETE object            clear object
DELETE TEX object        clear texture of object
DELETE BOUND object             clear bounding shape of object
BOUND object            automatic calculation of bounding shape

Assignments (with or without LET, "asn_expression")
---------------------------------------------------
object = string            associate object with string
object = vector_val        define position of object in space
object = obj_funct        object functions / other objects
TEX object = obj_funct        set texture
BOUND object = obj_funct    set bounding shape


Object Functions ("obj_funct"). Result is:
------------------------------------------
object                another object
TEX object            texture of an object
BOUND object            bounding shape of an object

PLANE (vector,vector)        plane with basis point and normal vector
PLANE (vector,vector,vector)    plane with three points

SCALE (object,vector)        scaled object
ROTATE (object,vector)        rotated object
TRANSLATE(object,vector)    translated object

SCALE# (object,vector)        scaled object (in object space)
ROTATE# (object,vector)        rotated object (in "object space")
TRANSLATE# (object,vector)    translated object (in object space)

CTDS(object,object)        connecting cone
CTDS(object,object,...)        union of connecting cones

UNION(object,object...)        union of objects
SECT(object,object...)        intersection of objects
DIFF(object,object...)        difference of objects

ADDOBJ(object,object...)    adding objects to an existing
                union, intersection or difference
                default: union